Co-Authored-By: shubhamvij <shubhamvij@users.noreply.github.com>

Co-Authored-By: shubhamvij <svij@snapchat.com>

…sisResult, FeatureProfileResult)

Co-Authored-By: shubhamvij <svij@snapchat.com>

Co-Authored-By: shubhamvij <svij@snapchat.com>

Implements the orchestration layer for BQ-based graph data quality checks:
- Tier 1 hard-fails (dangling edges, referential integrity, duplicate nodes)
  raise DataQualityError carrying a partially populated result.
- Tier 2 core metrics (counts, degree stats, top-K hubs, INT16 clamp, NULL
  rates) plus Python-side feature memory and neighbor-explosion estimates.
- Tier 3 label/heterogeneous checks auto-enabled by config (label_column
  presence; multiple edge tables).
- Tier 4 opt-in placeholders (power-law exponent from degree stats).

Co-Authored-By: shubhamvij <svij@snapchat.com>

Co-Authored-By: shubhamvij <svij@snapchat.com>

…assets

Co-Authored-By: shubhamvij <svij@snapchat.com>

Implements the report_generator module that stitches AI-owned template,
styles, and chart JS into a single self-contained HTML report by
replacing the four INJECT_* placeholders. Adds a golden-file snapshot
test (and four structural tests) so future AI-driven edits to the
report assets fail fast until the snapshot is regenerated. Registers
the *.ai.{html,js,css} assets as package-data so importlib.resources
can resolve them from an installed wheel.

Co-Authored-By: shubhamvij <svij@snapchat.com>

Implements the main orchestrator class that coordinates graph structure
analysis, feature profiling, and HTML report generation. Includes CLI
entry point with argparse for analyzer_config_uri and resource_config_uri.

Co-Authored-By: shubhamvij <svij@snapchat.com>

…deferred)

Co-Authored-By: shubhamvij <svij@snapchat.com>

Narrows the Union return type for mypy in the direct-merge test path.

Co-Authored-By: shubhamvij <svij@snapchat.com>

Co-Authored-By: shubhamvij <svij@snapchat.com>

Sits alongside SPEC.md to separate product requirements (why and what)
from technical implementation contract (how). Both are AI-owned and
together form the input for regenerating report.ai.html, charts.ai.js,
and styles.ai.css.

Co-Authored-By: shubhamvij <svij@snapchat.com>

Quickstart-first guide at gigl/analytics/README.md covering:

- 3-step quickstart (auth, YAML config, CLI command) with a single
  entry point that now writes report.html to disk or GCS
- Tier summary table (what runs when)
- Interpretation table with thresholds + "what to do" actions drawn
  from the 18-paper literature review
- Advanced config keys (opt-in Tier 3/4, label_column, timestamp_column,
  fan_out)
- Python API snippet for programmatic access
- graph_validation sub-package pointer
- Scope and limitations (FeatureProfiler stub, Tier 4 queries TODO)
- Links to design doc, literature review, 1-pager, engineering spec,
  report PRD, and report SPEC

Co-Authored-By: shubhamvij <svij@snapchat.com>

Changes from the review pass:

README fixes:
- Remove all docs/plans/* links (the plans were intentionally deleted
  in d3f1eb8). Inline the relevant paper citations into the threshold
  table so readers aren't pointed at 404s.
- Add "Prerequisites" line pointing at the GiGL installation guide so
  the quickstart doesn't assume uv/deps are already set up.
- Mark Tier 4 flags (compute_homophily, compute_connected_components,
  compute_clustering, timestamp_column) as not-yet-implemented in both
  the tier table and the Advanced Config section, not only in the
  Scope section at the bottom.
- Add the power-law exponent mention to the Tier 4 row (was only in
  scope notes; it's actually computed today).
- Document the heterogeneous-graph referential-integrity caveat
  (analyzer currently joins each edge table against node_tables[0]).
- Link to tests/test_assets/analytics/golden_report.html so a reader
  can preview the output before authenticating to BQ.

Config fix:
- NodeTableSpec.feature_columns: MISSING -> field(default_factory=list)
  so that nodes with no features are legal. Previously users got a
  cryptic OmegaConf MissingMandatoryValue error, and no-feature nodes
  are a real use case.
- Add a regression test covering the no-feature-columns case.

All 31 analytics unit tests pass. mypy clean. check_format clean.

Co-Authored-By: shubhamvij <svij@snapchat.com>